Hosting ipynb's on GitHub pages¶

WIP: so far, a pretty quickly thrown together jumble of notes

Preface¶

This is just 1 way to host an Rmd document. There are other options. This is just intended to show how to do it with GitHub pages, it is not claiming to GitHub pages to be the best route for all cases.

Step-by-step instructions¶

  • Make a Github repo

  • Make a notebook (ipynb file) you're proud of and want to share with the world!

  • Export the notebook to html

  • Name the html document index.html

  • Get the index.html file into your GitHub repo

    • Long term I recommend to find a Git+GitHub tutorial and learn how to interact with git. It's such a useful skill for so many different things!
      • here's a great one if you're just getting started with git
    • Short-term you can use the Add file button followed by clicking Upload files

  • Turn on GitHub pages for the repo by clicking:

    • Settings
    • Pages (under the Code and automation section in the sidebar)
    • Find the dropdown menu in the Branch section of the page and select "main" (there's a chance you want to select "master")
      • If you're new to GitHub there's probably only one option to choose, choose that one option that's not "None"
    • Click the Save button

  • Wait!

  • Find your website online at:https://<your-username>.github.io/<your-repo-name/

    • For example this repo is at https://github.com/AdamSpannbauer/hosting-ipynbs-with-GitHub-Pages/
      • This shows my user name is AdamSpannbauer
      • This shows my repo name is hosting-Rmds-with-GitHub-Pages
    • It's published GitHub pages site can is https://adamspannbauer.github.io/hosting-ipynbs-with-GitHub-Pages/

Exporting the notebook to HTML¶

Export menu¶

  • On jupyterlab - File > Save and Export Notebook As... > HTML
  • On the classic jupyter notebook editor - File > Download as > HTML
  • On vscode - Export > HTML
    • find the export button on the menu above your notebook (this menu has + Code, + Markdown, Run All, etc). You might have to click a ... button to find Export.

Exporting with nbconvert¶

The nbconvert tool can be used to create an index.html file and allow you to have some more customization options.

!jupyter nbconvert example.ipynb --no-input --to html --output index.html

[NbConvertApp] Converting notebook example.ipynb to html
[NbConvertApp] WARNING | Alternative text is missing on 1 image(s).
[NbConvertApp] Writing 3942544 bytes to index.html

The --no-input flag will make it so code doesn't appear in the output html file - remove --no-input if you want to show your code. If you just want to show just one or two python cell's code, you might consider code formatting in a markdown cell. There are other options available for toggling code cell visibility.

You can use jupyterlab themes to apply CSS theming to the output:

!pip install jupyterlab
!pip install jupyterlab_miami_nights

!jupyter nbconvert example.ipynb --no-input --to html --output index.html --theme jupyterlab_miami_nights

[NbConvertApp] Converting notebook example.ipynb to html
[NbConvertApp] WARNING | Alternative text is missing on 1 image(s).
[NbConvertApp] Writing 4340727 bytes to index.html

Putting contents in your notebook¶

Inlcuding a matplotlib made plot¶

No description has been provided for this image

Including a plotly made plot¶

To inlcude plotly graphics you need to initialize their notebook mode:

Sizing can be controlled to fixed pixel width & height.